home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / c / pmm / doku / libsdoku / metaxpr.dok < prev    next >
Text File  |  1999-06-14  |  35KB  |  680 lines
  1. ========================== metaxpr.library 4.0 ============================
  2. ===========================================================================
  3. Eine  Bibliothek,  die  Datentransfer  über xpr#?.library-Implementierungen
  4. erleichtert.  © Copyright 1991-92 by Olaf Barthel, alle Rechte vorbehalten.
  5.    Es   wird   keinerlei   Gewährleistungspflicht   für   die  vollständige
  6. Funktionsfähigkeit   der   in   diesem   Dokument   beschriebenen  Software
  7. übernommen.  Jegliche Nutzung geschieht auf eigene Gefahr.
  8.  
  9. Anmerkung (M.Prüß):
  10. GateXpr.Library ist eine veränderte Version (siehe History), entspricht
  11. aber in allen Punkten bis auf die Filegrößenermittlung dem Original.
  12.  
  13. =============================== Motivation ================================
  14. ===========================================================================
  15. Fast   alle   Programmierer,   die   sich  mit  der  Erstellung  von  Tele-
  16. kommunikationsoftware  beschäftigen,  stolpern  irgendwann  einmal über die
  17. xpr#?.libraries,  die  auf allgemeine Art und Weise Protokollle für Up- und
  18. Download implementieren.
  19.    An  dieser  Stelle  verläßt  die meisten Programmierer der Mut.  Wer hat
  20. schon  Lust,  eine  über  100 KBytes große Dokumentation (in Englisch!  wer
  21. spricht  schon  Englisch!)  durchzuarbeiten,  um  hinterher  doch nur einen
  22. Absturz zu Gesicht zu bekommen.
  23.    Nun  gibt  es  aber  dennoch Programmierer, die es geschafft haben, eine
  24. Implementierung  der  entsprechenden  Transferroutinen  zu  schreiben.  Das
  25. Resultat  sind  Programme,  die mit einem Satz Parameter von CLI oder Shell
  26. aufgerufen werden können.
  27.    Hier  liegt  der  Hund  begraben, denn soweit die Implementierung stabil
  28. ist,  so  ergeben  sich  beim  Aufruf Probleme:  Ist der Transfer geglückt?
  29. Wurde   das   Programm   eventuell   gar  nicht  geladen?   Wie  sehen  die
  30. Einstellungen des serial.device aus?
  31.    Hinzu   kommt   meist   noch,   daß   ein   Programm,  das  ein  solches
  32. Transferprogramm  aufrufen  will,  unbedingt  von CLI oder Shell aufgerufen
  33. werden muß.
  34.  
  35.    Vor  diesem  Hintergrund  habe ich mich entschlossen, eine Bibliothek zu
  36. schreiben,   die   externe   Programmaufrufe  für  die  Durchführung  eines
  37. Up-/Downloads  überflüssig  macht.   Weiterhin  hat das aufrufende Programm
  38. fast völlige Kontrolle über die Ansteuerung der seriellen Schnittstelle und
  39. die Möglichkeiten des Up-/Downloads.
  40.  
  41.  
  42. ==================== Bestandteile des MetaXPR-Paketes =====================
  43. ===========================================================================
  44. Die   folgenden  Dateien,  bzw.   Verzeichnisse  samt  Inhalt  gehören  zum
  45. MetaXPR-Paket:
  46.  
  47.    MetaXPR.dok..................... Die Dokumentation der Library
  48.  
  49.    metaxpr.library................. Die  Library  selbst  (auf allen  680x0
  50.                                     Prozessoren lauffähig)
  51.    metaxpr.library.020............. Die Library selbst (benötigt mindestens
  52.                                     einen  68020  Prozessor).  Um   sie  zu
  53.                                     installieren,   bitte   umbenennen   in
  54.                                     "metaxpr.library"
  55.    metaxpr_lib.fd.................. Funktionsdefinitionsdatei der Library
  56.  
  57.    MetaXPR.h....................... Header-Datei für `C' Programmierer
  58.  
  59.    Receive,Receive.c............... Beispielprogramm für das Empfangen  von
  60.                                     Dateien, in `C' geschrieben
  61.  
  62.    Send,Send.c..................... Beispielprogramm  für  das  Verschicken
  63.                                     von Dateien, in `C' geschrieben
  64.  
  65.    SendFiles,SendFiles.c........... Beispielprogramm  für  das  Verschicken
  66.                                     von mehreren Dateien,in `C' geschrieben
  67.  
  68.    LinkLibs/amigados_metaxpr.lib... Linker-Library im AmigaDOS-Objektformat
  69.    LinkLibs/manx36_metaxpr.lib..... Linker-Library für Aztec `C' 3.6
  70.    LinkLibs/manx50_metaxpr.lib..... Linker-Library für Aztec `C' 5.0
  71.    LinkLibs/sasc_metaxpr.lib....... Linker-Library für Lattice/SAS `C'
  72.  
  73.    Glue,SAS_Glue................... Quellcode zu den Linker-Libraries
  74.  
  75. ============================= Funktionsweise ==============================
  76. ===========================================================================
  77. Die Bibliothek metaxpr.library ist eine gewöhnliche Amiga-Systembibliothek,
  78. die  in  das LIBS:-Verzeichnis kopiert werden sollte.  Sie benimmt sich wie
  79. jede  andere  Bibliothek  (intuition.library, graphics.library, etc.).  Wer
  80. sich  mit  diesen  Bibliotheken abgerackert hat, der wird auch diese nutzen
  81. können.
  82.  
  83.    Nach   dem   Öffnen  der  Bibliothek  stehen  dem  Programmierer  sieben
  84. Funktionen zur Verfügung:
  85.  
  86.    TransferSetup......... Initialisiert  den  seriellen  Treiber und öffnet
  87.                           die  benötigte  xpr.library.   Diese  Routine muß
  88.                           aufgerufen   werden,  bevor  eine  der  folgenden
  89.                           Steuerroutinen aufgerufen wird.
  90.  
  91.    TransferSetupShared... Eine  in  Version  2.0 der Bibliothek eingeführte
  92.                           Funktion, die analog zu TransferSetup() arbeitet,
  93.                           es aber erlaubt, vom aufrufenden Programm bereits
  94.                           für   den   Datentransfer   geöffnete  Kanäle  zu
  95.                           verwenden,   anstatt  diese  von  der  Bibliothek
  96.                           öffnen zu lassen.
  97.  
  98.    InstallTransferNote... Diese   Funktion   wurde   in   Version  3.0  der
  99.                           Bibliothek   eingeführt   und   erlaubt  es,  den
  100.                           Transferroutinen  eine  Struktur zu übergeben, in
  101.                           der  Transferparameter  (wie  z.B.   verbleibende
  102.                           Übertragungsdauer   in   Sekunden   und  noch  zu
  103.                           übertragende Bytes) vermerkt werden und, wenn ein
  104.                           Struktureintrag   auf   0   gesetzt   wird,   den
  105.                           programmtechnischen    Abbruch    des   Transfers
  106.                           herbeiführt.
  107.  
  108.    ReceiveFile........... Empfängt  eine  Datei  unter Ausnutzung der durch
  109.                           TransferSetup/TransferSetupShared   eingestellten
  110.                           Parameter.
  111.  
  112.    SendFile.............. Verschickt  eine Datei unter Ausnutzung der durch
  113.                           TransferSetup/TransferSetupShared   eingestellten
  114.                           Parameter.
  115.  
  116.    SendMultipleFiles..... Diese   Funktion   wurde   in   Version  3.1  der
  117.                           Bibliothek  eingeführt  und dient zum Verschicken
  118.                           mehrerer Dateien am Stück.  Es werden wie bei der
  119.                           Funktion         `SendFile'        die        mit
  120.                           TransferSetup/TransferSetupShared   eingestellten
  121.                           Parameter benutzt.
  122.  
  123.    GetOptions............ Liest  die  für die aktuell geöffnete xpr.library
  124.                           eingestellten Parameter aus.
  125.  
  126.    SetOptions............ Setzt   die   internen   Parameter   der  aktuell
  127.                           geöffneten   xpr.library   (siehe   dazugehöriger
  128.                           Dokumentation).
  129.  
  130.    Im  folgenden  wird  auf  die  einzelnen  Routinen  und  deren Benutzung
  131. eingegangen:
  132.  
  133.                                      *
  134.  
  135. Fehler = TransferSetup(Treiber, Unit, Bibliothek, Baudrate, Datenbits,
  136.   D0                      A0     D0       A1        D1         D2
  137.  
  138.                        Stopbits, Parität, Handshaking)
  139.                           D3        D4        D5
  140.  
  141. Treiber         - Name    des    zu    benutzenden    seriellen    Treibers
  142.                   (serial.device, modem0.device, etc).  Wird als eine durch
  143.                   ein Nullbyte abgeschlossene Zeichenkette übergeben.
  144.  
  145. Unit            - Die   Treibereinheit,   die   angesprochen  werden  soll;
  146.                   entspricht  üblicherweise der Nummer des seriellen Ports,
  147.                   sollte  man  über keine Steckkarte mit mehreren seriellen
  148.                   Anschlüssen verfügen, so ist hier eine 0 einzutragen.
  149.  
  150. Bibliothek      - Der  Name  der  xpr.library, die für den Transfer benutzt
  151.                   werden  soll (xprzmodem.library, xprxmodem.library, etc).
  152.                   Der  Name  wird  als  durch  ein  Nullbyte abgeschlossene
  153.                   Zeichenkette übergeben.
  154.  
  155. Baurate         - Übertragungsgeschwindigkeit    in   Bits   pro   Sekunde.
  156.                   Gebräuchliche  Baudraten  bewegen  sich  zwischen 300 und
  157.                   31250 Baud.
  158.  
  159. Datenbits       - Die  Anzahl  Datenbits, die bei der Übertragung verwendet
  160.                   werden sollen.  Üblicherweise 8, manchmal auch 7.
  161.  
  162. Stopbits        - Die  Anzahl  Stopbits,  die bei der Übertragung verwendet
  163.                   werden sollen.  Üblicherweise 1, sonst auch 0 oder 2.
  164.  
  165. Parität         - Die  bei  der Übertragung zu verwendende Parität, gültige
  166.                   Werte sind:
  167.  
  168.                   0 - Keine Parität.
  169.                   1 - Gerade Parität.
  170.                   2 - Ungerade Partität.
  171.                   3 - Paritätsbit ist immer gesetzt.
  172.                   4 - Paritätsbit ist immer gelöscht.
  173.  
  174. Handshaking     - Gibt  an,  ob  Hardware-Handshaking  eingeschaltet werden
  175.                   soll (0 = aus, 1 = ein).
  176.  
  177.    Es  muß  darauf  hingewiesen  werden,  daß  diese  Routine den seriellen
  178. Treiber  exklusiv für sich öffnet.  Hat das aufrufende Programm den Treiber
  179. bereits  für  sich  belegt,  wird  der Aufruf dieser Funktion fehlschlagen!
  180. Wenn  man  diesen  Effekt vermeiden möchte, sollte man statt dieser Routine
  181. besser TransferSetupShared() verwenden.
  182.  
  183.    Der  von  dieser  Routine  geöffnete serielle Treiber wird erst nach dem
  184. Schließen der metaxpr.library freigegeben!
  185.  
  186.    Diese  Routine  liefert  einen  Wert  zurück, der gleich 0 ist, wenn die
  187. Initialisierungen  geglückt  sind  und ungleich 0, wenn die Initialisierung
  188. fehlgeschlagen   ist.    Anhand  des  zurückgelieferten  Wertes  läßt  sich
  189. entscheiden, welcher Fehler aufgetreten ist:
  190.  
  191.    1 - Einer oder mehrere an die Routine übergebenen Aufrufparameter waren
  192.        nicht zulässig.
  193.  
  194.    2 - Es konnte nicht genügend Speicher angefordert werden.
  195.  
  196.    3 - Beim Anlegen von MsgPorts ist ein Fehler aufgetreten (alle
  197.        Signalbits sind offenbar schon belegt).
  198.  
  199.    4 - Beim Öffnen des seriellen Treibers ist ein Fehler aufgetreten.
  200.  
  201.    5 - Die Parameter des seriellen Treibers ließen sich nicht setzen.
  202.  
  203.    6 - Der Zeitgeber (timer.device) ließ sich nicht öffnen.
  204.  
  205.    7 - Die zu verwendende xpr.library ließ sich nicht öffnen.
  206.  
  207.    8 - Die Initialisierung der xpr.library schlug fehl.
  208.  
  209.    9 - Wurden  die  Übertragungsparameter  über TransferSetup() gesetzt, so
  210.        können  sie  nur  über die selbe Routine verändert werden.  Gleiches
  211.        gilt für die Routine TransferSetupShared().
  212.  
  213.    Diese  Routine  selbst  läßt  sich  beliebig  oft  mit  neuen Parametern
  214. aufrufen.   Alle  hier  angeforderten  Resourcen  werden beim Schließen der
  215. Bibliothek wieder freigegeben.
  216.  
  217.                                      *
  218.  
  219. Fehler = TransferSetupShared(ReadRequest, WriteRequest, Bibliothek)
  220.   D0                             A0            A1           A2
  221.  
  222. ReadRequest     - Die  vom  aufrufenden  Programm  zum  Lesen von Daten der
  223.                   seriellen   Schnittstelle   verwendete  Struktur  (struct
  224.                   IOExtSer).
  225.  
  226. WriteRequest    - Die  vom  aufrufenden Programm zum Schicken von Daten zur
  227.                   seriellen   Schnittstelle   verwendete  Struktur  (struct
  228.                   IOExtSer).
  229.  
  230. Bibliothek      - Der  Name  der  xpr.library, die für den Transfer benutzt
  231.                   werden  soll (xprzmodem.library, xprxmodem.library, etc).
  232.                   Der  Name  wird  als  durch  ein  Nullbyte abgeschlossene
  233.                   Zeichenkette übergeben.
  234.  
  235.    Ein  Telekommunikationsprogramm  sollte  üblicherweise  mindestens  zwei
  236. Kanäle offen haben, um auf die seriellen Schnittstelle zugreifen zu können.
  237. Möchte man diese Kanäle nicht schließen (einige Modems legen z.B.  auf wenn
  238. die  vom serial.device aktivierte DTR-Leitung plötzlich abfällt), so bietet
  239. es  sich  an,  sie  dieser  Routine  zu  übergeben.  Vorsicht:  die Routine
  240. überprüft, ob ReadRequest und WriteRequest verschieden sind und liefert bei
  241. Übereinstimmung Fehlercode 1 zurück.
  242.    TransferSetupShared() verhält sich ansonsten genauso wie TransferSetup()
  243. und liefert dieselben Fehlercodes zurück.
  244.    Baudrate  oder  Parameter  von ReadRequest und WriteRequest werden nicht
  245. modifiziert.   Ich  empfehle  sowohl  vor  dem  Aufruf  dieser  Routine ein
  246. CMD_CLEAR an den seriellen Treiber zu schicken, als auch nach dem Schließen
  247. der   metaxpr.library.    Es  sollten  keine  Annahmen  über  die  Einträge
  248. io_Command,   io_Data,   io_Actual   oder  io_Length  von  ReadRequest  und
  249. WriteRequest gemacht werden, wenn die Routinen SendFile() und ReceiveFile()
  250. zurückkehren!
  251.  
  252.                                      *
  253.  
  254. Erfolg = ReceiveFile(Name, ÖffneFenster, Bildschirm)
  255.   D0                  A0       D0            A1
  256.  
  257.  
  258. Name            - Der  Name  der  zu empfangenden Datei.  Der Name wird als
  259.                   eine   durch  ein  Nullbyte  abgeschlossene  Zeichenkette
  260.                   übergeben.   In diese Zeichenkette wird auch der Name der
  261.                   zuletzt  übertragenen Datei eingetragen, die Zeichenkette
  262.                   sollte mindestens 256 Zeichen lang sein.
  263.                      Nach  Abschluß  der  Übertragung  befindet sich in der
  264.                   übergebenen   Zeichenkette   der   komplette   Name   der
  265.                   empfangenen  Datei  (der  sich  besonders  bei Kermit und
  266.                   ZModem  vom  übergebenen  Dateinamen unterscheiden wird).
  267.                   Die   dieser   Routine   übergebene  Zeichenkette  sollte
  268.                   mindestens 256 Zeichen lang sein.  Wurden mehrere Dateien
  269.                   empfangen,  so  enthält  diese Zeichenkette nur den Namen
  270.                   der zuletzt übertragenen Datei!
  271.  
  272. ÖffneFenster    - Bestimmt, ob während der Übertragung ein Fenster geöffnet
  273.                   werden  soll,  in dem Informationen über den Fortgang der
  274.                   Übertragung angezeigt werden.
  275.  
  276.                   0 = kein Fenster soll geöffnet werden.
  277.                   1 = ein Fenster soll geöffnet werden.
  278.                   2 = ein  Fenster  soll  geöffnet,  aber  nicht  aktiviert
  279.                       werden.
  280.  
  281. Bildschirm      - Dieser  Parameter operiert zusammen mit dem Parameter für
  282.                   `ÖffneFenster'.   Er bestimmt, auf welchem Bildschirm das
  283.                   Fenster  -  wenn  überhaupt - geöffnet werden soll.  Hier
  284.                   übergibt   man   die   Adresse  der  Screen-Struktur  des
  285.                   jeweiligen  Bildschirmes,  oder  den  Wert  NULL,  um das
  286.                   Fenster auf dem Workbench-Bildschirm zu öffnen.
  287.  
  288.    Diese  Routine  liefert  einen  Wert  zurück,  der  über  den Erfolg des
  289. Transfers  informiert.   Ist  dieser  Wert gleich 0, so ist die Übertragung
  290. fehlgeschlagen  oder  abgebrochen  worden.  Ist der Wert ungleich 0, so ist
  291. die Übertragung geglückt.
  292.  
  293.                                      *
  294.  
  295. Erfolg = SendFile(Name, ÖffneFenster, Bildschirm)
  296.   D0               A0       D0            A1
  297.  
  298.  
  299. Name            - Der  Name der zu verschickenden Datei.  Der Name wird als
  300.                   durch ein Nullbyte abgeschlossene Zeichenkette übergeben.
  301.                   In  diese  Zeichenkette  wird  auch  der Name der zuletzt
  302.                   übertragenen  Datei  eingetragen, die Zeichenkette sollte
  303.                   mindestens 256 Zeichen lang sein.
  304.  
  305. ÖffneFenster    - Bestimmt, ob während der Übertragung ein Fenster geöffnet
  306.                   werden  soll,  in dem Informationen über den Fortgang der
  307.                   Übertragung angezeigt werden.
  308.  
  309.                   0 = kein Fenster soll geöffnet werden.
  310.                   1 = ein Fenster soll geöffnet werden.
  311.                   2 = ein  Fenster  soll  geöffnet,  aber  nicht  aktiviert
  312.                       werden.
  313.  
  314. Bildschirm      - Dieser  Parameter operiert zusammen mit dem Parameter für
  315.                   `ÖffneFenster'.   Er bestimmt, auf welchem Bildschirm das
  316.                   Fenster  -  wenn  überhaupt - geöffnet werden soll.  Hier
  317.                   übergibt   man   die   Adresse  der  Screen-Struktur  des
  318.                   jeweiligen  Bildschirmes,  oder  den  Wert  NULL,  um das
  319.                   Fenster auf dem Workbench-Bildschirm zu öffnen.
  320.  
  321.    Diese  Routine  liefert  einen  Wert  zurück,  der  über  den Erfolg des
  322. Transfers  informiert.   Ist  dieser  Wert gleich 0, so ist die Übertragung
  323. fehlgeschlagen  oder  abgebrochen  worden.  Ist der Wert ungleich 0, so ist
  324. die Übertragung geglückt.
  325.  
  326.                                      *
  327.  
  328. Erfolg = SendMultipleFiles(Namen, ÖffneFenster, Bildschirm)
  329.   D0                        A0       D0            A1
  330.  
  331.  
  332. Name            - Die  Adresse  einer  Reihe von Adresswerten von mit einem
  333.                   Nullbyte    abgeschlossenen    Zeichenketten.    In   `C'
  334.                   entspräche      dies      z.B.       der     Konstruktion
  335.                   `char *Namen[123]', in anderen Sprachen kann man sich die
  336.                   verlangte  Datenstruktur  als  ein  Feld  von Langwörtern
  337.                   vorstellen,   von   denen   jedes   die   Adresse   einer
  338.                   Zeichenkette enthält:
  339.  
  340.                                  Feld[ 0 ] -> "Dateiname 0"
  341.                                  Feld[ 1 ] -> "Dateiname 1"
  342.                                  Feld[ 2 ] -> "Dateiname 2"
  343.  
  344.                                  :
  345.                                  :
  346.  
  347.                                  Feld[n-1] -> "Dateiname n-1"
  348.                                  Feld[ n ] -> 0
  349.  
  350.                      Wie man an dieser Tabelle schon sieht, muß der Adresse
  351.                   des  letzten  Dateinamens  eine  Null  folgen,  sodaß die
  352.                   Library  weiß,  welche  die  letzte zu übertragende Datei
  353.                   war.
  354.                      Der    Inhalt    dieses    Feldes    wird    von   der
  355.                   Übertragungsroutine nicht verändert.
  356.  
  357. ÖffneFenster    - Bestimmt, ob während der Übertragung ein Fenster geöffnet
  358.                   werden  soll,  in dem Informationen über den Fortgang der
  359.                   Übertragung angezeigt werden.
  360.  
  361.                   0 = kein Fenster soll geöffnet werden.
  362.                   1 = ein Fenster soll geöffnet werden.
  363.                   2 = ein  Fenster  soll  geöffnet,  aber  nicht  aktiviert
  364.                       werden.
  365.  
  366. Bildschirm      - Dieser  Parameter operiert zusammen mit dem Parameter für
  367.                   `ÖffneFenster'.   Er bestimmt, auf welchem Bildschirm das
  368.                   Fenster  -  wenn  überhaupt - geöffnet werden soll.  Hier
  369.                   übergibt   man   die   Adresse  der  Screen-Struktur  des
  370.                   jeweiligen  Bildschirmes,  oder  den  Wert  NULL,  um das
  371.                   Fenster auf dem Workbench-Bildschirm zu öffnen.
  372.  
  373.    Diese  Routine  liefert  einen  Wert  zurück,  der  über  den Erfolg des
  374. Transfers  informiert.   Ist  dieser  Wert gleich 0, so ist die Übertragung
  375. fehlgeschlagen  oder  abgebrochen  worden.  Ist der Wert ungleich 0, so ist
  376. die Übertragung geglückt.
  377.    Man   sollte   nicht   erwarten,   daß   sich   diese  Routine  auch  um
  378. Pattern-Matching  und  ähnlichen  Luxus kümmert, es wird immer versucht die
  379. jeweiligen   Dateien   unter   den   gegebenen   Namen   zu  öffnen.   Wird
  380. Pattern-Matching benötigt, so müssen die zu übertragenden Dateien ermittelt
  381. werden, bevor die Übertragung stattfindet.
  382.    Ob  diese  Funktion  ihren  Zweck  erfüllen  kann,  hängt  stark von der
  383. verwendeten  xpr.library  ab;  unterstützt  diese keinen Batch-Transfer, so
  384. wird zumindest versucht, die erste zu übertragende Datei zu verschicken.
  385.  
  386.                                      *
  387.  
  388. Erfolg = GetOptions(Puffer)
  389.   D0                  A0
  390.  
  391. Puffer          - Hier   werden  die  aktuell  eingestellten  Optionen  der
  392.                   geöffneten    xpr.library   abgelegt.    Es   wird   eine
  393.                   Zeichenkette  erwartet,  die  mindestens 256 Zeichen lang
  394.                   ist.
  395.  
  396.    Diese  Routine liefert einen Wert zurück, der über den Erfolg der Aktion
  397. informiert.   Ist dieser gleich 0, so konnten die Optionen nicht ausgelesen
  398. werden.   Ist er ungleich 0, so enthält der übergebene Puffer die mit einem
  399. Nullbyte abgeschlossenen aktuellen Optionen.
  400.  
  401.                                      *
  402.  
  403. Erfolg = SetOptions(Optionen)
  404.   D0                   A0
  405.  
  406. Optionen        - Die  zu  setzenden Optionen für die aktuelle xpr.library.
  407.                   Wird   als   mit  einem  Nullbyte  beendete  Zeichenkette
  408.                   erwartet.
  409.  
  410.    Diese  Routine liefert einen Wert zurück, der über den Erfolg der Aktion
  411. informiert.   Ist  dieser  gleich  0, so konnten die Optionen nicht gesetzt
  412. werden.  Ist er ungleich 0, so wurden die Optionen korrekt gesetzt.
  413.  
  414.                                      *
  415.  
  416. Fehler = InstallTransferNote(Note)
  417.   D0                          A0
  418.  
  419. Note            - Die  Adresse  einer  `C'-Struktur,  die man sich auch als
  420.                   eine Aufreihung von dreizehn Langwörtern vorstellen kann,
  421.                   sie sieht wie folgt aus:
  422.  
  423.                       struct TransferNote
  424.                       {
  425.                          LONG tn_Continue;     /* Ist dieser Wert gleich 0,
  426.                                                 * so wird der Transfer-
  427.                                                 * vorgang sofort ab-
  428.                                                 * gebrochen.
  429.                                                 */
  430.  
  431.                          LONG tn_CarrierDetect;/* Der Inhalt dieser Variable
  432.                                                 * gibt an, ob das Modem ein
  433.                                                 * Trägersignal (Carrier)
  434.                                                 * erkennt. Ist dieses Signal
  435.                                                 * nicht mehr vorhanden, ist
  436.                                                 * die Verbindung unterbrochen
  437.                                                 * worden.
  438.                                                 */
  439.  
  440.                          LONG tn_Seconds;      /* Anzahl der Sekunden, die
  441.                                                 * der Transfervorgang noch
  442.                                                 * dauern wird. Vorsicht!
  443.                                                 * dieser Wert kann von
  444.                                                 * Anfang an gleich 0 sein
  445.                                                 * und sich während des
  446.                                                 * gesamten Transfers
  447.                                                 * nicht verändern.
  448.                                                 */
  449.  
  450.                          LONG tn_Bytes;        /* Anzahl der noch zu
  451.                                                 * übertragenden Bytes.
  452.                                                 * Auch dieser Wert kann
  453.                                                 * von Anfang an gleich 0
  454.                                                 * sein und sich während
  455.                                                 * des gesamten Transfers
  456.                                                 * nicht verändern.
  457.                                                 */
  458.  
  459.                          APTR tn_UserData;     /* Ein Eintrag, der vom
  460.                                                 * Benutzer für seine
  461.                                                 * Zwecke verwendet
  462.                                                 * werden kann.
  463.                                                 */
  464.  
  465.                          char *tn_CurrentFile; /* Adresse einer Zeichenkette,
  466.                                                 * die den Namen der gerade
  467.                                                 * übertragenen Datei enthält.
  468.                                                 * Vorsicht: dieser Wert kann
  469.                                                 * auch NULL (0) sein, wenn
  470.                                                 * gerade keine Datei übertragen
  471.                                                 * wird.
  472.                                                 */
  473.  
  474.                          LONG tn_FilesToGo;    /* Soweit bekannt, enthält diese
  475.                                                 * Variable die Anzahl der noch
  476.                                                 * zu übertragenden Dateien
  477.                                                 * (0 = die letzte Datei wird
  478.                                                 * gerade verschickt).
  479.                                                 */
  480.  
  481.                          LONG tn_ProtocolName; /* Name einer Datei, in der die
  482.                                                 * Namen aller empfangenen und
  483.                                                 * verschickten Dateien eingetragen
  484.                                                 * werden. Steht hier eine Null,
  485.                                                 * so wird keine Protokolldatei
  486.                                                 * angelegt.
  487.                                                 */
  488.  
  489.                          LONG tn_Extension;    /* Anzahl der dieser Strukturform
  490.                                                 * noch folgenden Langwörter (für
  491.                                                 * künftige Erweiterungen reserviert).
  492.                                                 */
  493.  
  494.                          LONG tn_WatchCarrier; /* Sofern tn_Extension einen Wert >= 1
  495.                                                 * enthält, wird der Library über den
  496.                                                 * Inhalt dieses Langworts mitgeteilt,
  497.                                                 * ob bei Verlust des Trägersignals
  498.                                                 * der Transfer abgebrochen werden
  499.                                                 * soll. Falls Ja, ist hier eine 1,
  500.                                                 * falls Nein, eine 0 einzutragen.
  501.                                                 */
  502.  
  503.                          LONG tn_Aborted;      /* Sofern tn_Extension einen Wert >= 2
  504.                                                 * enthält, wird der Library über den
  505.                                                 * Inhalt dieses Langworts mitgeteilt,
  506.                                                 * ob der Transfer durch den Anwender
  507.                                                 * abgebrochen wurde.
  508.                                                 */
  509.  
  510.                          LONG tn_Error;        /* Sofern tn_Extension einen Wert >= 3
  511.                                                 * enthält, wird der Library über den
  512.                                                 * Inhalt dieses Langworts mitgeteilt,
  513.                                                 * ob der Transfer aufgrund eines
  514.                                                 * Fehlers abgebrochen wurde. Ist der
  515.                                                 * hier eingetragene Wert = 0, so ist
  516.                                                 * kein Fehler aufgetreten, ist er 1,
  517.                                                 * liegt ein AmigaDOS-Fehler vor, bei
  518.                                                 * 2 ist ein Schnittstellenfehler
  519.                                                 * aufgetreten.
  520.                                                 */
  521.  
  522.                          LONG tn_ErrorCode;    /* Sofern tn_Extension einen Wert >= 4
  523.                                                 * enthält, wird der Library über den
  524.                                                 * Inhalt dieses Langworts mitgeteilt,
  525.                                                 * aufgrund welchen Fehlers der Transfer
  526.                                                 * abgebrochen wurde. Dies ist entweder
  527.                                                 * ein AmigaDOS-Fehlercode, ein Fehlercode
  528.                                                 * der Schnittstelle oder der Wert 1000,
  529.                                                 * der angibt, daß das Carrier-Signal
  530.                                                 * verlorengegangen ist.
  531.                                                 */
  532.                       };
  533.  
  534.    Diese  Routine liefert einen Wert ungleich 0 zurück, wenn beim Eintragen
  535. ein   Fehler   aufgetreten  ist  (die  jeweiligen  Fehlerwerte  sind  unter
  536. `TransferSetup'  aufgeführt),  ein Wert gleich 0 wird zurückgeliefert, wenn
  537. kein Fehler aufgetreten ist.
  538.    Typischerweise  wird  diese Funktion von einem separat laufenden Process
  539. benutzt,  um  den  im Transfer befindlichen Process überwachen und notfalls
  540. abbrechen  zu  können.   Die übergebene `TransferNote'-Struktur muß während
  541. des    gesamten    Transfervorganges   erhalten   bleiben,   sonst   können
  542. Systemabstürze  die  Folge sein.  Der Bezug auf die Struktur bleibt bis zum
  543. Schließen   der  Library  oder  bis  zum  nächsten  Aufruf  der  Funktionen
  544. TransferSetupShared() und TransferSetup() erhalten.
  545.  
  546.    Zum   Format   der   Protokolldatei:    wird  eine  Datei  gelesen  oder
  547. beschrieben,  wenn  sie  verschickt  oder  empfangen wird, so wird ihr Name
  548. zusammen  mit  dem  jeweiligen  Zugriffsmodus  (`R'  für Empfangen, `S' für
  549. Verschicken)  in  die  Datei  geschrieben, deren Name unter tn_ProtocolName
  550. eingetragen  ist.   Typischerweise  sieht  der  Inhalt dieser Datei am Ende
  551. einer Übertragung folgendermaßen aus:
  552.  
  553.                       R Work:Download/EmpfangeDatei1
  554.                       R Work:Download/EmpfangeDatei2
  555.                                      :
  556.                                      :
  557.                                     etc.
  558.  
  559. An  die  unter  tn_ProtocolName  angegebene  Datei  werden  die  Namen  der
  560. empfangenen/verschickten    Dateien    _angehängt_,    sie   wird   _nicht_
  561. überschrieben.
  562.    Wird  eine  Datei  nicht korrekt verschickt/empfangen, so wird statt der
  563. Großbuchstaben "R" / "S" ein Kleinbuchstabe "r" / "s" vorangestellt.
  564.    Zum Schluß wird an die Liste der Dateinamen eine Zeile mit statistischen
  565. Daten angehängt, die folgenden Aufbau hat:
  566.  
  567.                + Files <Anzahl> Bytes <Anzahl> CPS <Anzahl>
  568.  
  569.    Es  wird  die  Anzahl  der  empfangenen Dateien, die Anzahl der empfang-
  570. enen  Dateien    und  die  durchschnittliche Übertragungsgeschwindigkeit in
  571. Zeichen pro Sekunde angegeben.
  572.                                      
  573. ================================ Anwendung ================================
  574. ===========================================================================
  575. Für  `C'  habe  ich  eine  Header-Datei  bereitgestellt, die Prototypen und
  576. Übergabewerte  enthält,  Linker-Bibliotheken sind ebenfalls vorhanden.  Für
  577. alle anderen Sprachen muß man sich mit der .fd-Datei behelfen.
  578.  
  579.        Die übliche Reihenfolge der Aufrufe sähe z.B. wie folgt aus:
  580.  
  581.         MetaXprBase = OpenLibrary("metaxpr.library",0);
  582.  
  583.         :
  584.         :
  585.  
  586.         Fehler = TransferSetup("serial.device",0,"xprzmodem.library",
  587.                                 2400,8,1,0,0);
  588.  
  589.         :
  590.         :
  591.  
  592.         Erfolg = ReceiveFile("Datei",0,0);
  593.  
  594.         :
  595.         :
  596.  
  597.         Erfolg = SendFile("Datei",1,Screen);
  598.  
  599.         :
  600.         :
  601.  
  602.         CloseLibrary(MetaXprBase);
  603.  
  604.    Wem  diese  paar Zeilen nicht helfen, der kann mir seine Fragen entweder
  605. brieflich, oder auf elektronischem Wege über Z-Net oder Usenet stellen.
  606.  
  607.  
  608. ====================== Anschrift & Bitte des Autors =======================
  609. ===========================================================================
  610. Die  Benutzung  der  metaxpr.library  ist  kostenfrei,  ich  verlange keine
  611. Spenden,  noch  erwarte  ich  sie.  Die einzige Auflage, die ich mache, ist
  612. die, daß jeder, der neue Supportroutinen für die Bibliothek schreibt, diese
  613. dem  MetaXPR-Paket hinzufügt, oder sie mir zuschickt.  Auf diese Weise soll
  614. Jedermann Zugang zur Nutzung der Bibliothek erhalten.
  615.  
  616.                              Meine Anschrift:
  617.  
  618.                                Olaf Barthel
  619.                              Brabeckstraße 35
  620.                             D-3000 Hannover 71
  621.  
  622.                         Z-Netz: O.BARTHEL@A-LINK-H
  623.                       Internet: olsen@sourcery.mxm.sub.org
  624.                                 o.barthel@a-link-h.comlink.de
  625.  
  626.  
  627. ========================= Entwicklungsgeschichte ==========================
  628. ===========================================================================
  629. V4.2    Da es inzwischen Versionen bis hoch zu 6.5 gibt und ich eine
  630.         Kollision vermeiden möchte wurde die Library umgetauft. Diese
  631.         Version trägt den Namen GateXpr.Library, ist aber ansonsten
  632.         identisch mit MetaXpr.Library 4.1a
  633. V4.1a   Einige kleinere Optimierungen in der Anpassung.
  634. V4.1    Anpassungen für Gateway-BBS by Michaela Prüß. Neue Berechnung der
  635.         Filegröße, da das Original und Aztec-C nicht miteinander harmo-
  636.         nierten. Danke an Olaf Barthel für die Quellen!
  637.  
  638. V4.0    Erweiterung   der   Überwachungsfunktionen,   verschiedene   Fehler
  639.         erschlagen.
  640.  
  641. V3.6-   Interne Versionen.
  642. V3.9
  643.  
  644. V3.5    Die Protokollierung der empfangenen und verschickten Dateien ist um
  645.         statistische   Daten  erweitert  worden.  Ebenfalls  ist  es  jetzt
  646.         möglich, den Transfer bei Verlust des Carrier-Signales abbrechen zu
  647.         lassen.
  648.  
  649. V3.4    Die   Library   unterstützt   andere   Treiber   als  das  Original
  650.         serial.device    jetzt   besser,   es   ist   jetzt   möglich,  die
  651.         Transferaktionen  in  einer  Datei mitprotokollieren zu lassen, das
  652.         Transferfenster kann jetzt auch inaktiv geöffnet werden.
  653.  
  654. V3.3    Einige  interne  Änderungen  sind  notwendig  geworden; die Library
  655.         meldet  jetzt  korrekt,  wenn ein Transfer abgebrochen wurde und es
  656.         erscheint  kein  AmigaDOS-Requester  mehr,  wenn  Diskettenprobleme
  657.         auftreten  (dieses  Feature ist zur Unterstützung der automatischen
  658.         Ausführung von Netcalls gedacht).
  659.  
  660. V3.1    Die  Library  wurde  wieder einmal um eine neue Funktion erweitert:
  661.         `SendMultipleFiles'      ist      hinzugekommen.       Auch     die
  662.         TransferNote-Struktur  ist  um einige Felder erweitert worden, auch
  663.         die Carrier-Erkennung sollte jetzt funktionieren.
  664.  
  665. V3.0    Die   Library   wurde   um   die  Funktion  `InstallTransferNote()'
  666.         erweitert.
  667.  
  668. V2.0    Es  gibt  die  neue  Funktion  `TransferSetupShared()', die Library
  669.         sollte  intern  jetzt etwas stabiler arbeiten, ein paar Fehler sind
  670.         beseitigt.
  671.  
  672. V1.2    Das Fenster verträgt sich auch mit anderen Systemfonts als topaz 8,
  673.         werden  andere  Tasten  als  ^C  oder  Escape  gedrückt,  hängt der
  674.         Transfervorgang  nicht  mehr,  die  Bibliothek läßt sich auch unter
  675.         Kickstart  2.0  öffnen.   Der Send und Receive übergebene Dateiname
  676.         enthält  nach  der  Übertragung  den Namen der zuletzt übertragenen
  677.         Datei.
  678.  
  679. V1.1    Erste öffentliche Verbreitung.
  680.